©Copyright 1995 Rogue Wave Software
Because C++ is still a young language, there is no standard way to structure a reference manual for a class or group of classes. The reference is presented here as an alphabetical listing of classes with their member and global functions grouped in categories according to their general use. The categories are not a part of the C++ language, but do provide a way of organizing the many functions.
Each class includes a brief description, an illustration showing its inheritance hierarchy, and a synopsis, indicating the header file(s) and Smalltalk typedef (if appropriate) associated with the class. The synopsis also shows a declaration and definition of a class object, and any typedefs that are used.
Member functions for each class are listed alphabetically. Member functions fall into three general types:
Throughout the documentation, there are frequent references to "self". This should be understood to mean "*this ".
RWCollectable<--RWCollection<--RWBTree<--RWBTreeDictionary
#include <rw/btrdict.h> RWBTreeDictionary a;
Dictionary class implemented as a B-Tree, for the storage and retrieval of key-value pairs. Both the keys and values must inherit abstract base class RWCollectable -- the elements are ordered internally according to the value returned by virtual function compareTo() of the key (see class RWCollectable). Duplicate keys are not allowed.
The B-Tree is balanced. That is, nodes are never allowed to have less than a certain number of items (called the order). The default order is 50, but may be changed by resetting the value of the static constant "order" in the header file <btree.h> and recompiling. Larger values will result in shallower trees, but less efficient use of memory.
Return to Top of File.typedef long RWstoredValue;
typedef int (*RWdiskTreeCompare)(const char*,
const char*,
size_t);
#include <rw/disktree.h>
#include <rw/filemgr.h>
RWFileManager fm("filename.dat");
RWBTreeOnDisk bt(fm);
Class RWBTreeOnDisk represents an ordered collection of associations of keys and values, where the ordering is determined by comparing keys using an external function. The user can set this function. Duplicate keys are not allowed. Given a key, the corresponding value can be found.
This class is specifically designed for managing a B-Tree in a disk file. Keys, defined to be arrays of chars, and values, defined by the typedef RWstoredValue, are stored and retrieved from a B-Tree. The values can represent offsets to locations in a file where objects are stored.
The key length is set by the constructor. By default, this value is 16 characters. By default, keys are null-terminated. However, the tree can be used with embedded nulls, allowing multibyte and binary data to be used as keys. To do so you must:
This class is meant to be used with class RWFileManager which manages the allocation and deallocation of space in a disk file.
When you construct an RWBTreeOnDisk you give the location of the root node in the constructor as argument start. If this value is RWNIL (the default) then the location will be retrieved from the RWFileManager using function start() (see class RWFileManager). You can also use the enumeration createMode to set whether to use an existing tree (creating one if one doesn"t exist) or to force the creation of a new tree. The location of the resultant root node can be retrieved using member function baseLocation().
More than one B-Tree can exist in a disk file. Each must have its own separate root node. This can be done by constructing more than one RWBTreeOnDisk, each with createMode set to create.
The order of the B-Tree can also be set in the constructor. Larger values will result in shallower trees, but less efficient use of disk space. The minimum number of entries in a node can also be set. Smaller values will result in less time spent balancing the tree, but less efficient use of disk space.
Return to Top of File.RWCollectable<--RWCollection<--RWBTree
#include <rw/btree.h> RWBTree a;
Class RWBTree represents a group of ordered elements, not accessible by an external key. Duplicates are not allowed. An object stored by class RWBTree must inherit abstract base class RWCollectable -- the elements are ordered internally according to the value returned by virtual function compareTo() (see class RWCollectable).
This class has certain advantages over class RWBinaryTree. First, the B-Tree is automatically balanced. (With class RWBinaryTree, you must call member function balance() explicitly to balance the tree.) Nodes are never allowed to have less than a certain number of items (called the order). The default order is 50, but may be changed by resetting the value of the static constant "order" in the header file <btree.h> and recompiling. Larger values will result in shallower trees, but less efficient use of memory.
Because many keys are held in a single node, class RWBTree also tends to fragment memory less.
Return to Top of File.RWIterator<--RWBagIterator
#include <rw/rwbag.h> RWBag b; RWBagIterator it(b);
Iterator for class RWBag, which allows sequential access to all the elements of RWBag. Note that because an RWBag is unordered, elements are not accessed in any particular order. If an item was inserted N times into the collection, then it will be visited N times.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.RWCollectable<--RWCollection<--RWBag
typedef RWBag Bag; // Smalltalk typedef. #include <rw/rwbag.h> RWBag h;
Class RWBag corresponds to the Smalltalk class Bag. It represents a group of unordered elements, not accessible by an external key. Duplicates are allowed.
An object stored by RWBag must inherit abstract base class RWCollectable, with suitable definition for virtual functions hash() and isEqual() (see class RWCollectable). The function hash() is used to find objects with the same hash value, then isEqual() is used to confirm the match.
Class RWBag is implemented by using an internal hashed dictionary ( RWHashDictionary) which keeps track of the number of occurrences of an item. If an item is added to the collection that compares equal (isEqual) to an existing item in the collection, then the count is incremented. Note that this means that only the first instance of a value is actually inserted: subsequent instances cause the occurrence count to be incremented. This behavior parallels the Smalltalk implementation of Bag.
Member function apply() and the iterator are called repeatedly according to the count for an item.
See class RWHashTable if you want duplicates to be stored, rather than merely counted.
Return to Top of File.#include <rw/bench.h> (Abstract base class)
This is an abstract class that can automate the process of benchmarking a piece of code. To use it, derive a class from RWBench, including a definition for the virtual function doLoop(unsigned long N). This function should perform N operations of the type that you are trying to benchmark. RWBench will call doLoop() over and over again until a preset amount of time has elapsed. It will then sum the total number of operations performed.
To run, construct an instance of your derived class and then call go(). Then call report() to get a standard summary. For many compilers, this summary will automatically include the compiler type and memory model. You can call ops(), outerLoops(), etc. for more detail.
If you wish to correct for overhead, then provide an idleLoop() function which should do non-benchmark related calculations.
Return to Top of File.RWIterator<--RWBinaryTreeIterator
// Smalltalk typedef: typedef RWBinaryTreeIterator SortedCollectionIterator; #include <rw/bintree.h> RWBinaryTree bt; RWBinaryTreeIterator iterate(bt);
Iterator for class RWBinaryTree. Traverses the tree from the "smallest" to "largest" element, where "smallest" and "largest" are defined by the virtual function compareTo(). Note that this approach is generally less efficient than using the member function RWBinaryTree::apply().
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.RWCollectable<--RWCollection<--RWBinaryTree
typedef RWBinaryTree SortedCollection; // Smalltalk typedef. #include <rw/bintree.h> RWBinaryTree bt;
Class RWBinaryTree represents a group of ordered elements, internally sorted by the compareTo() function. Duplicates are allowed. An object stored by an RWBinaryTree must inherit abstract base class RWCollectable.
Return to Top of File.#include <rw/bitvec.h> RWBitVec v;
Class RWBitVec is a bitvector whose length can be changed at run time. Because this requires an extra level of indirection, this makes it slightly less efficient than classes RWGBitVec(size) or RWTBitVec<size>, whose lengths are fixed at compile time.
Return to Top of File.RWVirtualPageHeap<--RWBufferedPageHeap
#include <rw/bufpage.h> (Abstract base class)
This is an abstract base class that represents an abstract page heap buffered through a set of memory buffers. It inherits from the abstract base class RWVirtualPageHeap which represents an abstract page heap.
RWBufferedPageHeap will supply and maintain a set of memory buffers. Specializing classes should supply the actual physical mechanism to swap pages in and out of these buffers by supplying definitions for the pure virtual functions swapIn(RWHandle, void*) and swapOut(RWHandle, void*).
The specializing class should also supply appropriate definitions for the public functions allocate() and deallocate(RWHandle).
For a sample implementation of a specializing class, see class RWDiskPageHeap.
Return to Top of File.streambuf<--RWCLIPstreambuf
#include <rw/winstrea.h> #include <iostream.h> iostream str( new RWCLIPstreambuf() );
Class RWCLIPstreambuf is a specialized streambuf that gets and puts sequences of characters to Microsoft Windows_ global memory. It can be used to exchange data through Windows clipboard facility.
The class has two modes of operation: dynamic and static. In dynamic mode, memory is allocated and reallocated on an as-needed basis. If too many characters are inserted into the internal buffer for its present size, then it will be resized and old characters copied over into any new memory as necessary. This is transparent to the user. It is expected that this mode would be used primarily for "insertions", i.e., clipboard "cuts" and "copies". In static mode, the buffer streambuf is constructed from a specific piece of memory. No reallocations will be done. It is expected that this mode would be used primarily for "extractions", i.e., clipboard "pastes".
In dynamic mode, the RWCLIPstreambuf "owns" any allocated memory until the member function str() is called, which "freezes" the buffer and returns an unlocked Windows handle to it. The effect of any further insertions is undefined. Until str() has been called, it is the responsibility of the RWCLIPstreambuf destructor to free any allocated memory. After the call to str(), it becomes the user's responsibility.
In static mode, the user has the responsibility for freeing the memory handle. However, because the constructor locks and dereferences the handle, you should not free the memory until either the destructor or str() has been called, either of which will unlock the handle.
Return to Top of File.#include <rw/regexp.h>
RWCRegexp re(".*\\.doc");// Matches filename with suffix ".doc"
Class RWCRegexp represents a regular expression. The constructor "compiles" the expression into a form that can be used more efficiently. The results can then be used for string searches using class RWCString.
The regular expression (RE) is constucted as follows:
The following rules determine one-character REs that match a single character:
+ * ? . [ ] ^ $
The following rules can be used to build a multicharacter RE.
Finally, the entire regular expression can be anchored to match only the beginning or end of a line:
The following escape codes can be used to match control characters:
\b backspace \e ESC (escape) \f formfeed \n newline \r carriage return \t tab \xddd the literal hex number 0xddd \^C Control code. E.g. \^D is "control-D"Return to Top of File.
#include <rw/cstring.h> RWCString a;
Class RWCString offers very powerful and convenient facilities for manipulating strings that are just as efficient as the familiar standard C <string.h> functions.
Although the class is primarily intended to be used to handle single-byte character sets (SBCS; such as ASCII or ISO Latin-1), with care it can be used to handle multibyte character sets (MBCS). There are two things that must be kept in mind when working with MBCS:
Parameters of type "const char*" must not be passed a value of zero. This is detected in the debug version of the library.
The class is implemented using a technique called copy on write. With this technique, the copy constructor and assignment operators still reference the old object and hence are very fast. An actual copy is made only when a "write" is performed, that is if the object is about to be changed. The net result is excellent performance, but with easy-to-understand copy semantics.
A separate class RWCSubString supports substring extraction and modification operations.
Return to Top of File.#include <rw/cstring.h>
RWCString s("test string");
s(6,3); // "tri"
The class RWCSubString allows some subsection of an RWCString to be addressed by defining a starting position and an extent. For example the 7"th through the 11"th elements, inclusive, would have a starting position of 7 and an extent of 5. The specification of a starting position and extent can also be done in your behalf by such functions as RWCString::strip() or the overloaded function call operator taking a regular expression as an argument. There are no public constructors -- RWCSubStrings are constructed by various functions of the RWCString class and then destroyed immediately.
A zero length substring is one with a defined starting position and an extent of zero. It can be thought of as starting just before the indicated character, but not including it. It can be used as an lvalue. A null substring is also legal and is frequently used to indicate that a requested substring, perhaps through a search, does not exist. A null substring can be detected with member function isNull(). However, it cannot be used as an lvalue.
Return to Top of File.#include <rw/ctoken.h>
RWCString str("a string of tokens");
RWCTokenizer(str); // Lex the above string
Class RWCTokenizer is designed to break a string up into separate tokens, delimited by an arbitrary "white space". It can be thought of as an iterator for strings and as an alternative to the ANSI C function strtok() which has the unfortunate side effect of changing the string being tokenized.
Return to Top of File.#include <rw/cacheman.h>
RWFile f("file.dat"); // Construct a file
RWCacheManager(&f, 100); // Cache 100 byte blocks to file.dat
Class RWCacheManager caches fixed length blocks to and from an associated RWFile. The block size can be of any length and is set at construction time. The number of cached blocks can also be set at construction time.
Writes to the file may be deferred. Use member function flush() to have any pending writes performed.
Return to Top of File.RWCollectable<--
RWCollectableString
RWCString<--
typedef RWCollectableString String; // Smalltalk typedef #include <rw/collstr.h> RWCollectableString c;
Collectable strings. This class is useful when strings are stored and retrieved as RWCollectables, or when they are used as keys in the "dictionary" collection classes. Class RWCollectableString inherits from both class RWCString and class RWCollectable. The virtual functions of the base class RWCollectable have been redefined.
Return to Top of File.RWCollectable<--
RWCollectableDate
RWDate<--
typedef RWCollectableDate Date; // Smalltalk typedef #include <rw/colldate.h> RWCollectableDate d;
Collectable Dates. Inherits classes RWDate and RWCollectable. This class is useful when dates are used as keys in the "dictionary" collection classes, or if dates are stored and retrieved as RWCollectables. The virtual functions of the base class RWCollectable have been redefined.
Return to Top of File.typedef RWCollectable Object; // Smalltalk typedef #include <rw/collect.h>
Class RWCollectable is an abstract base class for collectable objects. This class contains virtual functions for identifying, hashing, comparing, storing and retrieving collectable objects. While these virtual functions have simple default definitions, objects that inherit this base class will typically redefine one or more of them.
Return to Top of File.RWCollectable<--RWCollection
#include <rw/colclass.h> typedef RWCollection Collection; // Smalltalk typedef
Class RWCollection is an abstract base class for the Smalltalk_-like collection classes. The class contains virtual functions for inserting and retrieving pointers to RWCollectable objects into the collection classes. Virtual functions are also provided for storing and reading the collections to files and streams. Collections that inherit this base class will typically redefine one or more of these functions.
In the documentation below, pure virtual functions are indicated by "= 0" in their declaration. These functions must be defined in derived classes. For these functions the description is intended to be generic -- all inheriting collection classes generally follow the described pattern. Exceptions are noted in the documentation for the particular class.
For many other functions, a suitable definition is provided by RWCollection and a deriving class may not need to redefine the function. Examples are contains() or restoreGuts().
Return to Top of File.RWCollectable<--
RWCollectableInt
RWInteger<--
typedef RWCollectableInt Integer; // Smalltalk typedef #include <rw/collint.h> RWCollectableInt i;
Collectable integers. Inherits classes RWInteger and RWCollectable. This class is useful when integers are used as keys in the "dictionary" collection classes, or if integers are stored and retrieved as RWCollectables. The virtual functions of the base class RWCollectable have been redefined.
Return to Top of File.RWCollectable<--
RWCollectableTime
RWTime<--
typedef RWCollectableTime Time; // Smalltalk typedef #include <rw/colltime.h> RWCollectableTime t;
Inherits classes RWTime and RWCollectable. This class is useful when times are used as keys in the "dictionary" collection classes, or if times are stored and retrieved as RWCollectables. The virtual functions of the base class RWCollectable have been redefined.
Return to Top of File.streambuf<--RWCLIPstreambuf<--RWDDEstreambuf
#include <rw/winstrea.h> #include <iostream.h> iostream str( new RWDDEstreambuf(CF_TEXT, TRUE, TRUE, TRUE) );
Class RWDDEstreambuf is a specialized streambuf that gets and puts sequences of characters to Microsoft Windows_ global memory that has been allocated with the GMEM_DDESHARE flag. It can be used to exchange data through the Windows Dynamic Data Exchange (DDE) facility.
The class has two modes of operation: dynamic and static. In dynamic mode, memory is allocated and reallocated on an as-needed basis. If too many characters are inserted into the internal buffer for its present size, then it will be resized and old characters copied over into any new memory as necessary. This is transparent to the user. It is expected that this mode would be used primarily by the DDE server. In static mode, the buffer streambuf is constructed from a specific piece of memory. No reallocations will be done. It is expected that this mode would be used primarily by the DDE client.
In dynamic mode, the RWDDEstreambuf "owns" any allocated memory until the member function str() is called, which "freezes" the buffer and returns an unlocked Windows handle to it. The effect of any further insertions is undefined. Until str() has been called, it is the responsibility of the RWDDEstreambuf destructor to free any allocated memory. After the call to str(), it becomes the user's responsibility.
In static mode, the user always has the responsibility for freeing the memory handle. However, because the constructor locks and dereferences the handle, you should not free the memory until either the destructor or str() has been called, either of which will unlock the handle.
Note that although the user may have the "responsibility" for freeing the memory, whether it is the client or the server that actually does the call to GlobalFree() will depend on the DDE "release" flag.
Return to Top of File.#include <rw/rwdate.h> RWDate a; // Construct today's date
Class RWDate represents a date, stored as a Julian day number. The member function isValid() can be used to determine whether an RWDate is a valid date. For example, isValid() would return FALSE for the date 29 February 1991 because 1991 is not a leap year.
RWDate's can be converted to and from RWTime's, and to and from the Standard C library type struct tm defined in <time.h>.
Note that because the default constructor for this class creates an instance holding the current date, constructing a large array of RWDate may be slow. If this is an issue, declare your arrays with a class derived from RW Date that provides a faster constructor:
class FastDate : public RWDate
{
public:
FastDate() : RWDate(0) {;} // Constructs an "invalid" date by default
};
Also note that conversions between signed and unsigned can lead to unexpected results. Be sure to thoroughly test boundary conditions where applicable.
Return to Top of File.RWVirtualPageHeap<--RWBufferedPageHeap<--RWDiskPageHeap
#include <rw/diskpage.h>
unsigned nbufs;
unsigned pagesize;
RWDiskPageHeap heap("filename", nbufs, pagesize);
Class RWDiskPageHeap is a specializing type of buffered page heap. It swaps its pages to disk as necessary.
Return to Top of File.RWSequenceable<--RWCollection<--RWCollectable<--
RWDlistCollectables
RWSlist<--RWDlist<--
#include <rw/dlistcol.h> RWDlistCollectables a;
Class RWDlistCollectables represents a group of ordered items, not accessible by an external key. Duplicates are allowed. The ordering of elements is determined externally, generally by the order of insertion and removal. An object stored by RWDlistCollectables must inherit abstract base class RWCollectable.
Class RWDlistCollectables is implemented as a doubly-linked list, which allows for efficient insertion and removal, as well as for movement in either direction.
Return to Top of File.RWSlistIterator<--RWDlistIterator<--
RWDlistCollectablesIterator
RWIterator<--
#include <rw/dlistcol.h> RWDlistCollectables d; RWDlistCollectablesIterator it(d);
Iterator for class RWDlistCollectables. Traverses the linked-list from the first (head) to the last (tail) item. Functions are provided for moving in either direction.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.typedef unsigned short RWClassID; typedef RWCollectable* (*RWuserCreator)(); #include <rw/factory.h> RWFactory* theFactory;
Class RWFactory can create an instance of an RWCollectable object, given a class ID. It does this by maintaining a table of class ID"s and associated "creator function". A creator function has prototype:
RWCollectable* aCreatorFunction();
This function should create an instance of a particular class. For a given RWClassID tag, the appropriate function is selected, invoked and the resultant pointer returned. Because any object created this way is created off the heap, you are responsible for deleting it when done.
There is a one-of-a-kind global RWFactory pointed to by the pointer theFactory. It is guaranteed to have creator functions in it for all of the classes referenced by your program. See also Section 18.5.3.
Return to Top of File.#include <rw/rwfile.h>
RWFile f("filename");
Class RWFile encapsulates binary file operations using the Standard C stream library (functions fopen() , fread(), fwrite(), etc.). This class is based on class PFile of the Interviews Class Library (1987, Stanford University). The member function names begin with upper case letters in order to maintain compatibility with class PFile .
Because this class is intended to encapsulate binary operations, it is important that it be opened using a binary mode. This is particularly important under MS-DOS -- otherwise bytes that happen to match a newline will be expanded to (carriage return, line feed).
Return to Top of File.RWFile<--RWFileManager
typedef long RWoffset;
typedef unsigned long RWspace; // (typically)
#include <rw/filemgr.h>
RWFileManager f("file.dat");
Class RWFileManager allocates and deallocates storage in a disk file, much like a "freestore" manager. It does this by maintaining a linked list of free space within the file.
NOTE: Class RWFileManager inherits class RWFile as a public base class, hence all the public member functions of RWFile are visible to RWFileManager. They are not listed here.
If a file is managed by an RWFileManager then the results are undefined to read or write to an unallocated space in the file.
Return to Top of File.#include <rw/gbitvec.h> declare(RWGBitVec,size) RWGBitVec(size) a;
RWGBitVec(size) is a bit vector of fixed length size. The length cannot be changed dynamically (see class RWBitVec if you need a bit vector whose length can be changed at run time). Objects of type RWGBitVec(size) are declared with macros defined in the standard C++ header file <generic.h>.
Bits are numbered from 0 through size-1, inclusive.
Return to Top of File.RWSlist<--RWDlist<--RWGDlist(type)
#include <rw/gdlist.h> declare(RWGDlist, type) RWGDlist(type) a;
Class RWGDlist(type) represents a group of ordered elements of type type, not accessible by an external key. Duplicates are allowed. This class is implemented as a doubly-linked list. Objects of type RW GDlist(type) are declared with macros defined in the standard C++ header file <generic.h>.
In order to find a particular item within the collection, a user-provided global "tester" function is required to test for a "match", definable in any consistent way. This function should have prototype:
RWBoolean yourTesterFunction(const type* c, const void* d);
The argument c is a candidate within the collection to be tested for a match. The argument d is for your convenience and will be passed to yourTesterFunction(). The function should return TRUE if a "match" is found between c and d.
In order to simplify the documentation below, an imaginary typedef
typedef RWBoolean (*yourTester)(const type*, const void*);
has been used for this tester function.
Return to Top of File.
RWSlistIterator<--RWDlistIterator<--RWGDlistIterator(type)
#include <rw/gdlist.h> declare(RWGDlist, type) RWGDlist(type) a; RWGDlistIterator(type) I(a);
Iterator for class RWGDlist(type), which allows sequential access to all the elements of a doubly-linked list. Elements are accessed in order, in either direction.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
In order to simplify the documentation below, an imaginary typedef
typedef RWBoolean (*yourTester)(const type*, const void*);
has been used. See the documentation for class RWGDlist(type) for an explanation of this function.
Return to Top of File.#include <rw/gordvec.h> declare(RWGVector,val) declare(RWGOrderedVector,val) implement(RWGVector,val) implement(RWGOrderedVector,val) RWGOrderedVector(val) v;// Ordered vector of objects of type val.
Class RWGOrderedVector(val) represents an ordered collection of objects of type val. Objects are ordered by the order of insertion and are accessible by index. Duplicates are allowed. RWGOrderedVector(val) is implemented as a vector, using macros defined in the standard C++ header file <generic.h>.
Note that it is a value-based collection: items are copied in and out of the collection.
The class val must have:
To use this class you must declare and implement its base class as well as the class itself. For example, here is how you declare and implement an ordered collection of doubles:
declare(RWGVector,double) // Declare base class
declare(RWGOrderedVector,double) // Declare ordered vector
// In one and only one .cpp file you must put the following:
implement(RWGVector,double) // Implement base class
implement(RWGOrderedVector,double) // Implement ordered vector
For each type of RWGOrderedVector(val) you must include one (and only one) call to the macro implement somewhere in your code for both the RWGOrderedVector(val) itself and for its base class RWGVector(val).
Return to Top of File.RWSlist<--RWGQueue(type)
#include <rw/gqueue.h> declare(RWGQueue, type) RWGQueue(type) a;
Class RWGQueue(type) represents a group of ordered elements, not accessible by an external key. A RW GQueue(type) is a first in, first out (FIFO) sequential list for which insertions are made at one end (the "tail"), but all removals are made at the other (the "head"). Hence, the ordering is determined externally by the ordering of the insertions. Duplicates are allowed. This class is implemented as a singly-linked list. Objects of type RW GQueue(type) are declared with macros defined in the standard C++ header file <generic.h>.
In order to find a particular item within the collection, a user-provided global "tester" function is required to test for a "match", definable in any consistent way. This function should have prototype:
RWBoolean yourTesterFunction(const type* c, const void* d);
The argument c is a candidate within the collection to be tested for a match. The argument d is for your convenience and will be passed to yourTesterFunction(). The function should return TRUE if a "match" is found between c and d.
In order to simplify the documentation below, an imaginary typedef
typedef RWBoolean (*yourTester)(const type*, const void*);
has been used for this tester function.
Return to Top of File.RWSlistIterator<--RWGSlistIterator(type)
#include <rw/gslist.h> declare(RWGSlist, type) RWGSlist(type) a; RWGSlistIterator(type) I(a);
Iterator for class RWGSlist(type), which allows sequential access to all the elements of a singly-linked list. Elements are accessed in order, first to last.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
In order to simplify the documentation below, an imaginary typedef
typedef RWBoolean (*yourTester)(const type*, const void*);
has been used. See the documentation for class RWGSlist(type) for an explanation of this function.
Return to Top of File.RWSlist<--RWGSlist(type)
#include <rw/gslist.h> declare(RWGSlist, type) RWGSlist(type) a;
Class RWGSlist(type) represents a group of ordered elements of type type, not accessible by an external key. Duplicates are allowed. This class is implemented as a singly-linked list. Objects of type RW GSlist(type) are declared with macros defined in the standard C++ header file <generic.h>.
In order to find a particular item within the collection, a user-provided global "tester" function is required to test for a "match", definable in any consistent way. This function should have prototype:
RWBoolean yourTesterFunction(const type* c, const void* d);
The argument c is a candidate within the collection to be tested for a match. The argument d is for your convenience and will be passed to yourTesterFunction(). The function should return TRUE if a "match" is found between c and d.
In order to simplify the documentation below, an imaginary typedef
typedef RWBoolean (*yourTester)(const type*, const void*);
has been used for this tester function.
Return to Top of File.RWGVector(val)<--RWGSortedVector(val)
#include <rw/gsortvec.h> declare(RWGSortedVector,val) implement(RWGSortedVector, val) RWGSortedVector(val) v; // A sorted vector of val's.
Class RWGSortedVector(val) represents a vector of elements of type val, sorted using an insertion sort. The elements can be retrieved using an index or a search. Duplicates are allowed. Objects of type RW GSortedVector(val) are declared with macros defined in the standard C++ header file <generic.h>.
Note that it is a value-based collection: items are copied in and out of the collection.
The class val must have:
To use this class you must declare and implement its base class as well as the class itself. For example, here is how you declare and implement a sorted collection of doubles:
declare(RWGVector,double) // Declare base class
declare(RWGSortedVector,double) // Declare sorted vector
// In one and only one .cpp file you must put the following:
implement(RWGVector,double) // Implement base class
implement(RWGSortedVector,double) // Implement sorted vector
For each type of RWGSortedVector(val) you must include one (and only one) call to the macro implement somewhere in your code for both the RWGSortedVector(val) itself and for its base class RWGVector(val).
Insertions and retrievals are done using a binary search. Note that the constructor of an RWGSortedVector(val) requires a pointer to a "comparison function". This function should have prototype:
int comparisonFunction (const val* a, const val* b);
and should return an int less than, greater than, or equal to zero, depending on whether the item pointed to by a is less than, greater than, or equal to the item pointed to by b. Candidates from the collection will appear as a, the key as b.
Return to Top of File.RWSlist<--RWGStack(type)
#include <rw/gstack.h> declare(RWGStack,type) RWGStack(type) a;
Class RWGStack(type) represents a group of ordered elements, not accessible by an external key. A RW GStack(type) is a last in, first out (LIFO) sequential list for which insertions and removals are made at the beginning of the list. Hence, the ordering is determined externally by the ordering of the insertions. Duplicates are allowed. This class is implemented as a singly-linked list. Objects of type RWGStack(type) are declared with macros defined in the standard C++ header file <generic.h>.
In order to find a particular item within the collection, a user-provided global "tester" function is required to test for a "match", definable in any consistent way. This function should have prototype:
RWBoolean yourTesterFunction(const type* c, const void* d);
The argument c is a candidate within the collection to be tested for a match. The argument d is for your convenience and will be passed to yourTesterFunction(). The function should return TRUE if a "match" is found between c and d.
In order to simplify the documentation below, an imaginary typedef
typedef RWBoolean (*yourTester)(const type*, const void*);
has been used for this tester function.
Return to Top of File.#include <rw/gvector.h> declare(RWGVector,val) implement(RWGVector,val) RWGVector(val) a; // A Vector of val's.
Class RWGVector(val) represents a group of ordered elements, accessible by an index. Duplicates are allowed. This class is implemented as an array. Objects of type RWGVector(val) are declared with macros defined in the standard C++ header file <generic.h>.
Note that it is a value-based collection: items are copied in and out of the collection.
The class val must have:
For each type of RWGVector(val), you must include one (and only one) call to the macro implement, somewhere in your code.
Return to Top of File.RWIterator<--RWSetIterator<--RWHashDictionaryIterator
#include <rw/hashdict.h> RWHashDictionary hd; RWHashDictionaryIterator iter(hd);
Iterator for class RWHashDictionary, allowing sequential access to all the elements of RWHashDictionary. Since RWHashDictionary is unordered, elements are not accessed in any particular order.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.RWCollectable<--RWCollection<--RWHashTable<--RWSet<-- RWHashDictionary
typedef RWHashDictionary Dictionary; // Smalltalk typedef. #include <rw/hashdict.h> RWHashDictionary a;
A RWHashDictionary represents a group of unordered values, accessible by external keys. Duplicate keys are not allowed. Class RWHashDictionary is implemented as a hash table of associations of keys and values. Both the key and the value must inherit from the abstract base class RWCollectable, with a suitable definition of the virtual function hash() and isEqual() for the key.
This class corresponds to the Smalltalk class Dictionary.
Return to Top of File.RWIterator<--RWHashTableIterator
#include <rw/hashtab.h> RWHashTable h; RWHashTableIterator it(h);
Iterator for class RWHashTable, which allows sequential access to all the elements of RWHashTable. Note that because an RWHashTable is unordered, elements are not accessed in any particular order.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.RWCollectable<--RWCollection<--RWHashTable
#include <rw/hashtab.h> RWHashTable h;
This class is a simple hash table for objects inheriting from RWCollectable. It uses chaining (as implemented by class RWSlistCollectables) to resolve hash collisions. Duplicate objects are allowed.
An object stored by RWHashTable must inherit from the abstract base class RWCollectable, with suitable definition for virtual functions hash() and isEqual() (see class RWCollectable).
To find an object that matches a key, the key's virtual function hash() is first called to determine in which bucket the object occurs. The bucket is then searched linearly by calling the virtual function isEqual() for each candidate, with the key as the argument. The first object to return TRUE is the returned object.
The initial number of buckets in the table is set by the constructor. There is a default value. If the number of items in the collection greatly exceeds the number of buckets then efficiency will sag because each bucket must be searched linearly. The number of buckets can be changed by calling member function resize(). This will require that all objects be rehashed.
The iterator for this class is RWHashTableIterator.
Return to Top of File.RWCollectable<--RWCollection<--RWSet<--RWHashDictionary<-- RWIdentityDictionary
#include <rw/idendict.h> // Smalltalk typedef: typedef RWIdentityDictionary IdentityDictionary; RWIdentityDictionary a;
The class RWIdentityDictionary is implemented as a hash table, for the storage and retrieval of key-value pairs. Class RWIdentityDictionary is similar to class RWHashDictionary except that items are found by requiring that they be identical (i.e., have the same address) as the key, rather than being equal (i.e., test true for isEqual()).
Both keys and values must inherit from the abstract base class RWCollectable.
The iterator for this class is RWHashDictionaryIterator.
Return to Top of File.RWCollectable<--RWCollection<--RWSet<--RWIdentitySet
#include <rw/idenset.h> typedef RWIdentitySet IdentitySet; // Smalltalk typedef RWIdentitySet a;
The class RWIdentitySet is similar to class RWSet except that items are found by requiring that they be identical (i.e., have the same address) as the key, rather than being equal (i.e., test true for isEqual()).
The iterator for this class is RWSetIterator.
Return to Top of File.#include <rw/rwint.h> RWInteger i;
Integer class. This class is useful as a base class for classes that use integers as keys in dictionaries, etc.
Return to Top of File.#include <rw/iterator.h> typedef RWIterator Iterator; // "Smalltalk" typedef
Class RWIterator is an abstract base class for iterators used by the Smalltalk_-like collection classes. The class contains virtual functions for positioning and resetting the iterator. They are all pure virtual functions, meaning that deriving classes must supply a definition. The descriptions below are intended to be generic -- all inheriting iterators generally follow the described pattern.
Return to Top of File.#include <locale.h> #include <rw/locale.h> (Abstract base class)
RWLocale is an abstract base class. It defines an interface for formatting dates (including day and month names), times, numbers (including digit grouping), and currency, to and from strings.
Note that because it is an abstract base class, there is no way to actually enforce these goals -- the description here is merely the model of how a class derived from RWLocale should act.
There are three ways to use an RWLocale object:
Two implementations of RWLocale are provided with the library: RWLocaleSnapshot and RW LocaleDefault.
RWLocale<--RWLocaleSnapshot
#include <locale.h>
#include <rw/locale.h>
RWLocaleSnapshot ourLocale(""); // encapsulate user's formats
The class RWLocaleSnapshot implements the RWLocale interface using Standard C library facilities. To use it, the program creates an RWLocaleSnapshot instance. The constructor of the instance queries the program's environment (using standard C library functions such as localeconv(), strftime(), and, if available , vendor specific library functions) to learn everything it can about formatting conventions in effect at the moment of instantiation. When done, the locale can then be switched and another instance of RWLocaleSnapshot created. By creating multiple instances of RWLocaleSnapshot, your program can have more than one locale active at the same time, something that is difficult to do with the Standard C library facilities.
NOTE: RWLocaleSnapshot does not encapsulate character set, collation, or message information.
Class RWLocaleSnapshot has a set of public data members initialized by its constructor with information extracted from its execution environment.
Return to Top of File.#include <rw/model.h> (abstract base class)
This abstract base class has been designed to implement the "Model" leg of a Model-View-Controller architecture. A companion class, RWModelClient, supplies the "View" leg.
It maintains a list of dependent RWModelClient objects.When member function changed(void*) is called, the list of dependents will be traversed, calling updateFrom(RWModel*, void*) for each one, with itself as the first argument. Classes subclassing off RWModelClient should be prepared to accept such a call.
Return to Top of File.#include <rw/model.h> (abstract base class)
This abstract base class has been designed to implement the "View" leg of a Model-View-Controller architecture. Class RWModel, supplies the "Model" leg. See class RWModel for details.
Return to Top of File.RWCollectable<--RWCollection<--RWSequenceable<--RWOrdered
#include <rw/ordcltn.h> RWOrdered a;
Class RWOrdered represents a group of ordered items, accessible by an index number, but not accessible by an external key. Duplicates are allowed. The ordering of elements is determined externally, generally by the order of insertion and removal. An object stored by RWOrdered must inherit from the abstract base class RWCollectable.
Class RWOrdered is implemented as a vector of pointers, allowing for more efficient traversing of the collection than the linked list classes. RWSlistCollectables and RWDlistCollectables, but slower insertion in the center of the collection.
Return to Top of File.RWIterator<--RWOrderedIterator
#include <rw/ordcltn.h> RWOrdered a; RWOrderedIterator iter(a);
Iterator for class RWOrdered. Traverses the collection from the first to the last item.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.RWCollectable<--RWCollection<--RWSequenceable
#include <rw/seqcltn.h> typedef RWSequenceable SequenceableCollection; // Smalltalk typedef
Class RWSequenceable is an abstract base class for collections that can be accessed via an index. It inherits class RWCollection as a public base class and adds a few extra virtual functions. This documentation only describes these extra functions.
Return to Top of File.RWCollectable<--RWCollection<--RWHashTable<--RWSet
typedef RWSet Set; // Smalltalk typedef. #include <rw/rwset.h> RWSet h;
Class RWSet represents a group of unordered elements, not accessible by an external key, where duplicates are not allowed. It corresponds to the Smalltalk class Set.
An object stored by RWSet must inherit abstract base class RWCollectable, with suitable definition for virtual functions hash() and isEqual() (see class RWCollectable). The function hash() is used to find objects with the same hash value, then isEqual() is used to confirm the match.
An item c is considered to be "already in the collection" if there is a member of the collection for which isEqual© returns TRUE. In this case, the message insert© will not add it, thus insuring that there are no duplicates.
The iterator for this class is RWSetIterator.
Return to Top of File.RWIterator<--RWHashTableIterator<--RWSetIterator
#include <rw/rwset.h> RWSet h; RWSetIterator it(h);
Iterator for class RWSet, which allows sequential access to all the elements of RWSet. Note that because an RWSet is unordered, elements are not accessed in any particular order.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.RWCollectable<--RWCollection<--RWSequenceable<--
RWSlistCollectables
RWSlist<--
// Smalltalk typedef: typedef RWSlistCollectables LinkedList; #include <rw/slistcol.h> RWSlistCollectables a;
Class RWSlistCollectables represents a group of ordered elements, without keyed access. Duplicates are allowed. The ordering of elements is determined externally, by the order of insertion and removal. An object stored by RWSlistCollectables must inherit abstract base class RWCollectable.
The virtual function isEqual() (see class RWCollectable) is required to find a match between a target and an item in the collection
Class RWSlistCollectables is implemented as a singly-linked list, which allows for efficient insertion and removal, but efficient movement in only one direction. This class corresponds to the Smalltalk class LinkedList.
Return to Top of File.RWCollectable<--RWCollection<--RWSequenceable<--
RWSlistCollectables<--RWSlistCollectablesQueue
RWSlist<--
// Smalltalk typedef: typedef RWSlistCollectablesQueue Queue; #include <rw/queuecol.h> RWSlistCollectablesQueue a;
Class RWSlistCollectablesQueue represents a restricted interface to class RWSlistCollectables to implement a first in first out (FIFO) queue. A Queue is a sequential list for which all insertions are made at one end (the "tail"), but all removals are made at the other end (the "head"). Hence, the ordering is determined externally by the ordering of the insertions. Duplicates are allowed.
An object stored by RWSlistCollectablesQueue must inherit abstract base class RWCollectable. The virtual function isEqual() (see class RWCollectable) is required to find a match between a target and an item in the queue.
This class corresponds to the Smalltalk class Queue.
Return to Top of File.RWCollectable<--RWCollection<--RWSequenceable<--
RWSlistCollectables<--RWSlistCollectablesStack
RWSlist<--
// Smalltalk typedef: typedef RWSlistCollectablesStack Stack; #include <rw/stackcol.h> RWSlistCollectablesStack a;
Class RWSlistCollectablesStack represents a restricted interface to class RWSlistCollectables to implement a last in first out (LIFO) stack. A Stack is a sequential list for which all insertions and deletions are made at one end (the beginning of the list). Hence, the ordering is determined externally by the ordering of the insertions. Duplicates are allowed.
An object stored by RWSlistCollectablesStack must inherit abstract base class RWCollectable. The virtual function isEqual() (see class RWCollectable) is required to find a match between a target and an item in the stack.
This class corresponds to the Smalltalk class Stack.
Return to Top of File.RWIterator<--
RWSlistCollectablesIterator
RWSlistIterator<--
// Smalltalk typedef. typedef RWSlistCollectablesIterator LinkedListIterator; #include <rw/slistcol.h> RWSlistCollectables sc; RWSlistCollectablesIterator sci(sc);
Iterator for class RWSlistCollectables. Traverses the linked-list from the first to last item.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.RWCollectable<--RWCollection<--RWSequenceable<--RWOrdered<-- RWSortedVector
#include <rw/sortvec.h> RWSortedVector a;
Class RWSortedVector represents a group of ordered items, internally sorted by the compareTo() function and accessible by an index number. Duplicates are allowed. An object stored by RWSortedVector must inherit from the abstract base class RWCollectable. An insertion sort is used to maintain the vector in sorted order.
Because class RWSortedVector is implemented as a vector of pointers, traversing the collection is more efficient than with class RWBinaryTree. However, insertions are slower in the center of the collection.
Note that because the vector is sorted, you should not modify elements while contained in the vector in such a way as to invalidate the ordering.
Return to Top of File.#include <rw/tbitvec.h> RWTBitVec<22> // A 22 bit long vector
RWTBitVec<size> is a parameterized bit vector of fixed length size. Unlike class RWBitVec, its length cannot be changed at run time. Its advantage of RWBitVec is its smaller size, and one less level of indirection, resulting in a slight speed advantage.
Bits are numbered from 0 through size-1, inclusive.
The copy constructor and assignment operator use copy semantics.
Return to Top of File.#include <rw/tislist.h> RWTIsvSlist<T> list; RWTIsvSlistIterator<T> iterator(list);
Iterator for class RWTIsvSlist<T>, allowing sequential access to all the elements of a singly-linked parameterized intrusive list. Elements are accessed in order, from first to last.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.#include <rw/tislist.h> RWTIsvSlist<T> list;
Class RWTIsvSlist<T> is a class that implements intrusive singly-linked lists.
An intrusive list is one where the member of the list must inherit from a common base class, in this case RW IsvSlist. The advantage of such a list is that memory and space requirements are kept to a minimum. The disadvantage is that the inheritance hierarchy is inflexible, making it slightly more difficult to use with an existing class. Class RWTValSlist<T> is offered as an alternative, non-intrusive, linked list.
See Stroustrup (1991; Section 8.3.1) for more information about intrusive lists.
Note that when you insert an item into an intrusive list, the actual item (not a copy) is inserted. Because each item carries only one link field, the same item cannot be inserted into more than one list, nor can it be inserted into the same list more than once.
Return to Top of File.#include <rw/tidlist.h> RWTIsvDlist<T> list;
Class RWTIsvDlist<T> is a class that implements intrusive doubly-linked lists.
An intrusive list is one where the member of the list must inherit from a common base class, in this case RW IsvDlink. The advantage of such a list is that memory and space requirements are kept to a minimum. The disadvantage is that the inheritance hierarchy is inflexible, making it slightly more difficult to use with an existing class. Class RWTValDlist<T> is offered as an alternative, non-intrusive, linked list.
See Stroustrup (1991; Section 8.3.1) for more information about intrusive lists.
Note that when you insert an item into an intrusive list, the actual item (not a copy) is inserted. Because each item carries only one link field, the same item cannot be inserted into more than one list, nor can it be inserted into the same list more than once.
Return to Top of File.#include <rw/tidlist.h> RWTIsvDlist<T> list; RWTIsvDlistIterator<T> iterator(list);
Iterator for class RWTIsvDlist<T>, allowing sequential access to all the elements of a doubly-linked parameterized intrusive list. Elements are accessed in order, in either direction.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.#include <rw/tpdlist.h> RWTPtrDlist<T> list;
This class maintains a collection of pointers to type T, implemented as a doubly linked list. This is a
pointer based list: pointers to objects are copied in and out of the links that make up the list.
Parameter T represents the type of object to be inserted into the list, either a class or built in type.
The class T must have:
#include <rw/tpsrtvec.h> RWTPtrSortedVector<T> sortvec;
RWTPtrSortedVector<T> is a pointer-based ordered collection. That is, the items in the collection have a meaningful ordered relationship with respect to each other and can be accessed by an index number. In the case of RWTPtrSortedVector<T>, objects are inserted such that objects "less than" themselves are before the object, objects "greater than" themselves after the object. An insertion sort is used. Duplicates are allowed.
Stores a pointer to the inserted item into the collection according to an ordering determined by the less-than (<) operator.
The class T must have:
#include <rw/tphasht.h> unsigned hashFun(const T&); RWTPtrHashTable<T> table(hashFun);
This class implements a parameterized hash table of types T. It uses chaining to resolve hash collisions. Duplicates are allowed.
It is a pointer based collection: pointers to objects are copied in and out of the hash buckets.
Parameter T represents the type of object to be inserted into the table, either a class or built in type.
The class T must have:
A user-supplied hashing function for type T must be supplied to the constructor when creating a new table.
If T is a Rogue Wave class, then this requirement is usually trivial because all Rogue Wave
objects know how to return a hashing value. This function has prototype:
unsigned hFun(const T& a);
and should return a suitable hash value for the object a.
To find an object, it is first hashed to determine in which bucket it occurs. The bucket is then searched for an object that is equal (as determined by the equality operator) to the candidate.
The initial number of buckets in the table is set by the constructor. There is a default value. If the number of items in the collection greatly exceeds the number of buckets then efficiency will sag because each bucket must be searched linearly. The number of buckets can be changed by calling member function resize(). This is relatively expensive because all of the keys must be rehashed.
If you wish for this to be done automatically, then you can subclass from this class and implement your own special insert() and remove() functions which perform a resize() as necessary.
Return to Top of File.RWTPtrHashTable<T><--RWTPtrHashSet<T>
#include <rw/tphset.h> unsigned hashFun(const T&); RWTPtrHashSet(hashFun) set;
RWTPtrHashSet<T> is a derived class of RWTPtrHashTable<T> where the insert() function has been overridden to accept only one item of a given value. Hence, each item in the collection will have a unique value.
As with class RWTPtrHashTable<T>, you must supply a hashing function to the constructor.
The class T must have:
#include <rw/tpvector.h> RWTPtrVector<T> vec;
Class RWTPtrVector<T> is a simple parameterized vector of pointers to objects of type T.
It is most useful when you know precisely how many objects have to be held in the collection. If the intention is to
"insert" an unknown number of objects into a collection, then class
RWTPtrOrderedVector<T> may be a better choice.
The class T can be of any type.
#include <rw/tpordvec.h> RWTPtrOrderedVector<T> ordvec;
RWTPtrOrderedVector<T> is a pointer-based ordered collection. That is, the items in the collection have a meaningful ordered relationship with respect to one another and can be accessed by an index number. The order is set by the order of insertion. Duplicates are allowed. The class is implemented as a vector, allowing efficient insertion and retrieval from the end of the collection, but somewhat slower from the beginning of the collection.
The class T must have:
#include <rw/tpdlist.h> RWTPtrDlist<T> list; RWTPtrDlistIterator<T> iterator(list);
Iterator for class RWTPtrDlist<T>, allowing sequential access to all the elements of a doubly-linked parameterized list. Elements are accessed in order, in either direction.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.#include <rw/tphdict.h> unsigned hashFun(const K&); RWTPtrHashDictionary<K,V> dictionary(hashFun); RWTPtrHashDictionaryIterator<K,V> iterator(dictionary);
Iterator for class RWTPtrHashDictionary<K,V>, allowing sequential access to all keys and values of a parameterized hash dictionary. Elements are not accessed in any particular order.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.#include <rw/tpslist.h> RWTPtrSlist<T> list;
This class maintains a collection of pointers to type T, implemented as a singly-linked list. This is a
pointer based list: pointers to objects are copied in and out of the links that make up the list.
Parameter T represents the type of object to be inserted into the list, either a class or built in type.
The class T must have:
#include <rw/tphasht.h> RWTPtrHashTable<T> table; RWTPtrHashTableIterator<T> iterator(table);
Iterator for class RWTPtrHashTable<T>, allowing sequential access to all the elements of a hash table. Elements are not accessed in any particular order.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.#include <rw/tphdict.h> unsigned hashFun(const K&); RWTPtrHashDictionary<K,V> dictionary(hashFun);
RWTPtrHashDictionary<K,V> is a dictionary of keys of type K and values of type V
, implemented using a hash table. While duplicates of values are allowed, duplicates of keys are not.
It is a pointer based collection: pointers to the keys and values are copied in and out of the hash buckets.
Parameters K and V represent the type of the key and the type of the value, respectively, to be
inserted into the table. These can be either classes or built in types. Class K must have
Class V can be of any type.
A user-supplied hashing function for type K must be supplied to the constructor when creating a new table.
If K is a Rogue Wave class, then this requirement is usually trivial because all Rogue Wave
objects know how to return a hashing value. This function has prototype:
unsigned hFun(const K& a);
and should return a suitable hash value for the object a.
To find a value, the key is first hashed to determine in which bucket the key and value can be found. The bucket is then searched for an object that is equal (as determined by the equality operator) to the key.
The initial number of buckets in the table is set by the constructor. There is a default value. If the number of (key/value) pairs in the collection greatly exceeds the number of buckets then efficiency will sag because each bucket must be searched linearly. The number of buckets can be changed by calling member function resize(). This is relatively expensive because all of the keys must be rehashed.
If you wish for this to be done automatically, then you can subclass from this class and implement your own special insert() and remove() functions which perform a resize() as necessary.
Return to Top of File.#include <rw/tpslist.h> RWTPtrSlist<T> list; RWTPtrSlistIterator<T> iterator(list);
Iterator for class RWTPtrSlist<T>, allowing sequential access to all the elements of a singly-linked parameterized list. Elements are accessed in order, from first to last.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.#include <rw/tqueue.h> RWTQueue<T, C> queue;
This class represents a parameterized queue. Not only can the type of object inserted into the queue be parameterized, but also the implementation.
Parameter T represents the type of object in the queue, either a class or built in type. The class T
must have:
C.Parameter C represents the class used for implementation. Useful choices are
RWTValSlist<T> or
RWTValDlist<T>. Vectors, such as
RWTValOrderedVector<T>, can also be used, but tend to be less efficient
at removing an object from the front of the list.
#include <rw/tstack.h> RWTStack<T, C> stack;
This class maintains a stack of values. Not only can the type of object inserted onto the stack be parameterized, but also the implementation of the stack.
Parameter T represents the type of object in the stack, either a class or built in type. The class T
must have:
C.Parameter C represents the class used for implementation. Useful choices are
RWTValOrderedVector<T> or
RWTValDlist<T>. Class
RWTValSlist<T> can also be used, but note that singly-linked lists are
less efficient at removing the last item of a list (function pop()), because of the necessity of searching the list
for the next-to-the-last item.
#include <rw/tvdlist.h> RWTValDlist<T> list; RWTValDlistIterator<T> iterator(list);
Iterator for class RWTValDlist<T>, allowing sequential access to all the elements of a doubly-linked parameterized list. Elements are accessed in order, in either direction.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.#include <rw/tvdlist.h> RWTValDlist<T> list;
This class maintains a collection of values, implemented as a doubly linked list. This is a value based list: objects are copied in and out of the links that make up the list. Unlike intrusive lists (see class RWTIsvDlist<T>), the objects need not inherit from a link class. However, this makes the class slightly less efficient than the intrusive lists because of the need to allocate a new link off the heap with every insertion and to make a copy of the object in the newly allocated link.
Parameter T represents the type of object to be inserted into the list, either a class or built in type.
The class T must have:
#include <rw/tvhdict.h> unsigned hashFun(const K&); RWTValHashDictionary<K,V> dictionary(hashFun);
RWTValHashDictionary<K,V> is a dictionary of keys of type K and values of type V
, implemented using a hash table. While duplicates of values are allowed, duplicates of keys are not.
It is a value based collection: keys and values are copied in and out of the hash buckets.
Parameters K and V represent the type of the key and the type of the value, respectively, to be
inserted into the table. These can be either classes or built in types. Classes K and V must
have:
K must haveA user-supplied hashing function for type K must be supplied to the constructor when creating a new table.
If K is a Rogue Wave class, then this requirement is usually trivial because all Rogue Wave
objects know how to return a hashing value. This function has prototype:
unsigned hFun(const K& a);
and should return a suitable hash value for the object a.
To find a value, the key is first hashed to determine in which bucket the key and value can be found. The bucket is then searched for an object that is equal (as determined by the equality operator) to the key.
The initial number of buckets in the table is set by the constructor. There is a default value. If the number of (key/value) pairs in the collection greatly exceeds the number of buckets then efficiency will sag because each bucket must be searched linearly. The number of buckets can be changed by calling member function resize(). This is an expensive proposition because not only must all the items be copied into the new buckets, but all of the keys must be rehashed.
If you wish this to be done automatically, then you can subclass from this class and implement your own special insert() and remove() functions which perform a resize() as necessary.
Return to Top of File.#include <rw/tvordvec.h> RWTValOrderedVector<T> ordvec;
RWTValOrderedVector<T> is an ordered collection. That is, the items in the collection have a meaningful ordered relationship with respect to one another and can be accessed by an index number. The order is set by the order of insertion. Duplicates are allowed. The class is implemented as a vector, allowing efficient insertion and retrieval from the end of the collection, but somewhat slower from the beginning of the collection.
The class T must have:
Note that an ordered vector has a length (the number of items returned by length() or entries())
and a capacity. Necessarily, the capacity is always greater than or equal to the length. Although elements beyond
the collection's length are not used, nevertheless, in a value-based collection, they are occupied. If each instance of
class T requires considerable resources, then you should ensure that the collection"s capacity is not much
greater than its length, otherwise unnecessary resources will be tied up.
RWTValHashTable<T><--RWTValHashSet<T>
#include <rw/tvhset.h> unsigned hashFun(const T&); RWTValHashSet(hashFun) set;
RWTValHashSet<T> is a derived class of RWTValHashTable<T> where the insert() function has been overridden to accept only one item of a given value. Hence, each item in the collection will be unique.
As with class RWTValHashTable<T>, you must supply a hashing function to the constructor.
The class T must have:
#include <rw/tvsrtvec.h> RWTValSortedVector<T> sortvec;
RWTValSortedVector<T> is an ordered collection. That is, the items in the collection have a meaningful ordered relationship with respect to each other and can be accessed by an index number. In the case of RW TValSortedVector<T>, objects are inserted such that objects "less than" themselves are before the object, objects "greater than" themselves after the object. An insertion sort is used. Duplicates are allowed.
Stores a copy of the inserted item into the collection according to an ordering determined by the less-than (<) operator.
The class T must have:
Note that a sorted vector has a length (the number of items returned by length() or entries())
and a capacity. Necessarily, the capacity is always greater than or equal to the length. Although elements beyond
the collection's length are not used, nevertheless, in a value-based collection, they are occupied. If each instance of
class T requires considerable resources, then you should ensure that the collection"s capacity is not much
greater than its length, otherwise unnecessary resources will be tied up.
#include <rw/tvvector.h> RWTValVector<T> vec;
Class RWTValVector<T> is a simple parameterized vector of objects of type T. It is most
useful when you know precisely how many objects have to be held in the collection. If the intention is to "insert" an
unknown number of objects into a collection, then class
RWTValOrderedVector<T> may be a better choice.
The class T must have:
#include <rw/tvhdict.h> unsigned hashFun(const K&); RWTValHashDictionary<K,V> dictionary(hashFun); RWTValHashDictonaryIterator<K,V> iterator(dictionary);
Iterator for class RWTValHashDictionary<K,V>, allowing sequential access to all keys and values of a parameterized hash dictionary. Elements are not accessed in any particular order.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.#include <rw/tvhasht.h> RWTValHashTable<T> table; RWTValHashTableIterator<T> iterator(table);
Iterator for class RWTValHashTable<T>, allowing sequential access to all the elements of a hash table. Elements are not accessed in any particular order.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.#include <rw/tvslist.h> RWTValSlist<T> list;
This class maintains a collection of values, implemented as a singly linked list. This is a value based list: objects are copied in and out of the links that make up the list. Unlike intrusive lists (see class RWTIsvSlist<T>) the objects need not inherit from a link class. However, this makes the class slightly less efficient than the intrusive lists because of the need to allocate a new link off the heap with every insertion and to make a copy of the object in the newly allocated link.
Parameter T represents the type of object to be inserted into the list, either a class or built in type.
The class T must have:
#include <rw/tvhasht.h> unsigned hashFun(const T&); RWTValHashTable<T> table(hashFun);
This class implements a parameterized hash table of types T. It uses chaining to resolve hash collisions.
Duplicates are allowed.
It is a value based collection: objects are copied in and out of the hash buckets.
Parameter T represents the type of object to be inserted into the table, either a class or built in type.
The class T must have:
A user-supplied hashing function for type T must be supplied to the constructor when creating a new table.
If T is a Rogue Wave class, then this requirement is usually trivial because all Rogue Wave
objects know how to return a hashing value. This function has prototype:
unsigned hFun(const T& a);
and should return a suitable hash value for the object a.
To find an object, it is first hashed to determine in which bucket it occurs. The bucket is then searched for an object that is equal (as determined by the equality operator) to the candidate.
The initial number of buckets in the table is set by the constructor. There is a default value. If the number of items in the collection greatly exceeds the number of buckets then efficiency will sag because each bucket must be searched linearly. The number of buckets can be changed by calling member function resize(). This is an expensive proposition because not only must all items be copied into the new buckets, but they must also be rehashed.
If you wish this to be automatically done, then you can subclass from this class and implement your own special insert() and remove() functions which perform a resize() as necessary.
Return to Top of File.#include <rw/tvslist.h> RWTValSlist<T> list; RWTValSlistIterator<T> iterator(list);
Iterator for class RWTValSlist<T>, allowing sequential access to all the elements of a singly-linked parameterized list. Elements are accessed in order, from first to last.
Like all Rogue Wave iterators, the "current item" is undefined immediately after construction -- you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid -- continuing to use it will bring undefined results.
Return to Top of File.#include <rw/tvrtarry.h> RWVirtualPageHeap* heap; RWTValVirtualArray<T> array(1000L, heap);
This class represents a virtual array of elements of type T of almost any length. Individual elements are
brought into physical memory on an "as needed" basis. If an element is used as an lvalue it is automatically marked as
"dirty" and will be rewritten to the swapping medium.
The swap space is provided by an abstract page heap which is specified by the constructor. Any number of virtual arrays can use the same abstract page heap. You must take care that the destructor of the abstract page heap is not called before all virtual arrays built from it have been destroyed.
The class supports reference counting using a copy-on-write technique, so (for example) returning a virtual array by value from a function is as efficient as it can be. Be aware, however, that if the copy-on-write machinery finds that a copy must ultimately be made, then for large arrays this could take quite a bit of time.
For efficiency, more than one element can (and should) be put on a page. The actual number of elements is equal to the page size divided by the element size, rounded downwards. Example: for a page size of 512 bytes, and an element size of 8, then 64 elements would be put on a page.
The indexing operator (operator[](long)) actually returns an object of type RWTVirtualElement<T>. Consider this example:
double d = vec[j]; vec[i] = 22.0;
Assume that vec is of type RWTValVirtualArray<double>. The expression vec[j] will
return an object of type RWTVirtualElement<double>, which will contain a reference to the element being
addressed. In the first line, this expression is being used to initialize a double. The class RW
TVirtualElement<T> contains a type conversion operator to convert itself to a T, in this case a
double. The compiler uses this to initialize d. In the second line, the expression vec[i] is being used
as an lvalue. In this case, the compiler uses the assignment operator for RWTVirtualElement<T>. This
assignment operator recognizes that the expression is being used as an lvalue and automatically marks the appropriate page
as "dirty", thus guaranteeing that it will be written back out to the swapping medium.
Slices, as well as individual elements, can also be addressed. These should be used wherever possible as they are much more efficient because they allow a page to be locked and used multiple times before unlocking.
The class T must have:
In addition, you must never take the address of an element.
Return to Top of File.#include <rw/rwtime.h> RWTime a; // Construct with current time
Class RWTime represents a time, stored as the number of seconds since 00:00:00 January 1, 1901 UTC. See Section 8 for how to set the time zone for your compiler. Failure to do this may result in UTC (GMT) times being wrong.
Output formatting is done using an RWLocale object. The default locale formats according to U.S. conventions.
Note that because the default constructor for this class creates an instance holding the current time, constructing a large array of RWTime may be slow. If this is an issue, declare your arrays with a class derived from RW Time that provides a faster constructor:
class FastTime : public RWTime
{public:
FastTime() : RWTime(0) {;} // Constructs an "invalid" time by default
};
Return to
Top of File.
#include <rw/timer.h> RWTimer timer;
This class can measure elapsed CPU (user) time. The timer has two states: running and stopped. The timer measures the total amount of time spent in the "running" state since it was either constructed or reset.
The timer is put into the "running" state by calling member function start(). It is put into the "stopped" state by calling stop().
Return to Top of File.#include <rw/vpage.h> (Abstract base class)
This is an abstract base class representing an abstract page heap of fixed sized pages. The following describes the model by which specializing classes of this class are expected to work.
You allocate a page off the abstract heap by calling member function allocate() which will return a memory "handle", an object of type RWHandle. This handle logically represents the page.
In order to use the page it must first be "locked" by calling member function lock() with the handle as an argument. It is the job of the specializing class of RWVirtualPageHeap to make whatever arrangements are necessary to swap in the page associated with the handle and bring it into physical memory. The actual swapping medium could be disk, expanded or extended memory, or a machine someplace on a network. Upon return, lock() returns a pointer to the page, now residing in memory.
Once a page is in memory, you are free to do anything you want with it although if you change the contents, you must call member function dirty() before unlocking the page.
Locked pages use up memory. In fact, some specializing classes may have only a fixed number of buffers in which to do their swapping. If you are not using the page, you should call unlock(). After calling unlock() the original address returned by lock() is no longer valid -- to use the page again, it must be locked again with lock().
When you are completely done with the page then call deallocate() to return it to the abstract heap.
In practice, managing this locking and unlocking and the inevitable type casts can be difficult. It is usually easier to design a class than can work with an abstract heap to bring things in and out of memory automatically. Indeed, this is what has been done with class RWTValVirtualArray<T>, which represents a virtual array of elements of type T. Elements are automatically swapped in as necessary as they are addressed.
Return to Top of File.#include <rw/wstring.h> RWWString a;
Class RWWString offers very powerful and convenient facilities for manipulating wide character strings.
This string class manipulates wide characters of the Standard C type wchar_t. These characters are generally two or four bytes, and can be used to encode richer code sets than the classic "char" type. Because wchar_t characters are all the same size, indexing is fast.
Conversion to and from multibyte and ASCII forms are provided by the RWWString constructors, and by the RWWString member functions isAscii(), toAscii(), and toMultiByte().
Stream operations implicitly translate to and from the multibyte stream representation. That is, on output, wide character strings are converted into multibyte strings, while on input they are converted back into wide character strings. Hence, the external representation of wide character strings is usually as multibyte character strings, saving storage space and making interfaces with devices (which usually expect multibyte strings) easier.
Class RWWString tolerates embedded nulls.
Parameters of type "const wchar_t*" must not be passed a value of zero. This is detected in the debug version of the library.
The class is implemented using a technique called copy on write. With this technique, the copy constructor and assignment operators still reference the old object and hence are very fast. An actual copy is made only when a "write" is performed, that is if the object is about to be changed. The net result is excellent performance, but with easy-to-understand copy semantics.
A separate RWWSubString class supports substring extraction and modification operations.
Return to Top of File.#include <rw/wstring.h> RWWString s(L"test string"); s(6,3); // "tri"
The class RWWSubString allows some subsection of an RWWString to be addressed by defining a starting position and an extent. For example the 7"th through the 11"th elements, inclusive, would have a starting position of 7 and an extent of 5. The specification of a starting position and extent can also be done in your behalf by such functions as RWWString::strip() or the overloaded function call operator taking a regular expression as an argument. There are no public constructors -- RWWSubStrings are constructed by various functions of the RWWString class and then destroyed immediately.
A zero lengthed substring is one with a defined starting position and an extent of zero. It can be thought of as starting just before the indicated character, but not including it. It can be used as an lvalue. A null substring is also legal and is frequently used to indicate that a requested substring, perhaps through a search, does not exist. A null substring can be detected with member function isNull(). However, it cannot be used as an lvalue.
Return to Top of File.#include <rw/wtoken.h>
RWWString str("a string of tokens", RWWString::ascii);
RWWTokenizer(str); // Lex the above string
Class RWWTokenizer is designed to break a string up into separate tokens, delimited by an arbitrary "white space". It can be thought of as an iterator for strings and as an alternative to the C library function wstok() which has the unfortunate side effect of changing the string being tokenized.
Return to Top of File.RWvios<--RWvostream<--
RWXDRostream
RWios<--
#include <rw/xdrstrea.h> XDR xdr; xdrstdio_create(&xdr, stdout, XDR_ENCODE); RWXDRostream rw_xdr(&xdr);
Class RWXDRostream is a portable output stream based on XDR routines. Class RWXDRostream encapsulates a portion of the XDR library routines that are used for external data representation. XDR routines allow programmers to describe arbitrary data structures in a machine-independent fashion. Data for remote procedure calls (RPC) are transmitted using XDR routines.
Class RWXDRostream enables one to output from a stream and encode an XDR structure from a machine representation. Class RWXDRostream provides the capability to encode the standard data types and vectors of those data types.
An XDR stream must first be created by calling the appropriate creation routine. XDR streams currently exist for encoding/decoding of data to or from standard I/O FILE streams, TCP/IP connections and Unix files, and memory. These creation routines take arguments that are tailored to the specific properties of the stream. After the XDR stream has been created, it can then be used as an argument to the constructor for a RWXDRostream object.
RWXDRostream can be interrogated as to the status of the stream using member functions bad(), clear(), eof(), fail(), good(), and rdstate().
Return to Top of File.RWvios<--RWvistream<--
RWXDRistream
Rwios<--
#include <rw/xdrstrea.h> XDR xdr; xdrstdio_create(&xdr, stdin, XDR_DECODE); RWXDRistream rw_xdr(&xdr);
Class RWXDRistream is a portable input stream based on XDR routines. Class RWXDRistream encapsulates a portion of the XDR library routines that are used for external data representation. XDR routines allow programmers to describe arbitrary data structures in a machine-independent fashion. Data for remote procedure calls (RPC) are transmitted using XDR routines.
Class RWXDRistream enables one to decode an XDR structure to a machine representation. Class RW XDRistream provides the capability to decode all the standard data types and vectors of those data types.
An XDR stream must first be created by calling the appropriate creation routine. XDR streams currently exist for encoding/decoding of data to or from standard I/O FILE streams, TCP/IP connections and Unix files, and memory. These creation routines take arguments that are tailored to the specific properties of the stream. After the XDR stream has been created, it can then be used as the argument to the constructor for a RWXDRistream object.
RWXDRistream can be interrogated as to the status of the stream using member functions bad(), clear(), eof(), fail(), good(), and rdstate().
Return to Top of File.RWZone<--RWZoneSimple
#include <time.h> #include <rw/zone.h> RWZoneSimple myZone(USCentral);
RWZoneSimple is an implementation of the abstract interface defined by class RWZone. It implements a simple daylight savings time rule sufficient to represent all historical U.S. conventions and many European and Asian conventions. It is table-driven and depends on parameters given by class RWDaylightRule.
Direct use of RWDaylightRule affords the most general interface to RWZoneSimple. However, a much simpler programmatic interface is offered, as illustrated by the examples below.
Three instances of RWZoneSimple are automatically constructed at program startup, to represent UTC, Standard, and local time. They are available via calls to the static member functions RWZone::utc(), RWZone::standard(), and RWZone::local(), respectively. These are set up according to the time zone facilities provided in the execution environment (typically defined by the environment variable TZ). By default, if DST is observed at all, then the local zone instance will use U.S. (RWZone::NoAm) daylight savings time rules.
Other instances of RWZoneSimple may be constructed to represent other time zones, and may be installed globally using RWZone static member functions RWZone::local(const RWZone*) and RWZone::standard(const RWZone*).
Return to Top of File.#include <time.h> #include <rw/zone.h> (abstract base class)
RWZone is an abstract base class. It defines an interface for time zone issues such as whether or not daylight savings time is in use, the names and offsets from UTC (also known as GMT) for both standard and daylight savings times, and the start and stop dates for daylight savings time, if used.
Note that because it is an abstract base class, there is no way to actually enforce these goals -- the description here is merely the model of how a class derived from RWZone should act.
Most programs interact with RWZone only by passing an RWZone reference to an RWTime or RWDate member function that expects one.
RWZoneSimple is an implementation of the abstract RWZone interface sufficient to represent U.S.A. daylight savings time rules. Three instances of RWZoneSimple are initialized from the global environment at program startup to represent local, standard, and universal time. They are available via calls to the static member functions RWZone::local(), RWZone::standard(), and RWZone::utc(), respectively. See the class RWZoneSimple for details.
Return to Top of File.RWvios<--RWvistream<--
RWbistream
ios<--
#include <rw/bstream.h> RWbistream bstr(cin); // Construct an RWbistream, // using cin's streambuf
Class RWbistream specializes the abstract base class RWvistream to restore variables stored in binary format by RWbostream.
You can think of it as a binary veneer over an associated streambuf. Because the RWbistream retains no information about the state of its associated streambuf, its use can be freely exchanged with other users of the streambuf (such as an istream or ifstream).
RWbistream can be interrogated as to the stream state using member functions good(), bad() , eof(), etc.
Return to Top of File.RWvios<--RWvostream<--
RWbostream
ios<--
#include <rw/bstream.h> // Construct an RWbostream, using cout's streambuf: RWbostream bstr(cout);
Class RWbostream specializes the abstract base class RWvostream to store variables in binary format. The results can be restored by using its counterpart RWbistream.
You can think of it as a binary veneer over an associated streambuf. Because the RWbostream retains no information about the state of its associated streambuf, its use can be freely exchanged with other users of the streambuf (such as ostream or ofstream).
Note that variables should not be separated with whitespace. Such whitespace would be interpreted literally and would have to be read back in as a character string.
RWbostream can be interrogated as to the stream state using member functions good(), bad() , eof(), etc.
Return to Top of File. Return to Top of File.RWvios<--RWvistream<--RWpistream
#include <rw/pstream.h> RWpistream pstr(cin); // Construct an RWpistream, using cin's // streambuf
Class RWpistream specializes the abstract base class RWvistream to restore variables stored in a portable ASCII format by RWpostream.
You can think of RWpistream and RWpostream as an ASCII veneer over an associated streambuf which are responsibile for formatting variables and escaping characters such that the results can be interchanged between any machines. As such, they are slower than their binary counterparts RWbistream and RWbostream which are more machine dependent. Because RWpistream and RWpostream retain no information about the state of their associated streambufs, their use can be freely exchanged with other users of the streambuf (such as istream or ifstream).
RWpistream can be interrogated as to the stream state using member functions good(), bad() , eof(), etc.
Return to Top of File.RWvios<--RWvostream<--RWpostream
#include <rw/pstream.h> // Construct an RWpostream, using cout's streambuf: RWpostream pstr(cout);
Class RWpostream specializes the abstract base class RWvostream to store variables in a portable (printable) ASCII format. The results can be restored by using its counterpart RWpistream.
You can think of RWpistream and RWpostream as an ASCII veneer over an associated streambuf which are responsbile for formatting variables and escaping characters such that the results can be interchanged between any machines. As such, they are slower than their binary counterparts RWbistream and RWbostream which are more machine dependent. Because RWpistream and RWpostream retain no information about the state of their associated streambufs, their use can be freely exchanged with other users of the streambuf (such as istream or ifstream).
The goal of class RWpostream and RWpistream is to store variables using nothing but printable ASCII characters. Hence, nonprintable characters must be converted into an external representation where they can be recognized. Furthermore, other characters may be merely bit values (a bit image, for example), having nothing to do with characters as symbols. For example,
RWpostream pstrm(cout); char c = "\n"; pstr << c; // Stores "newline" pstr.put©; // Stores the number 10.
The expression "pstr << c" treats c as a symbol for a newline, an unprintable character. The expression "pstr.put©" treats c as the literal number "10".
Note that variables should not be separated with whitespace. Such whitespace would be interpreted literally and would have to be read back in as a character string.
RWpostream can be interrogated as to the stream state using member functions good(), bad() , eof(),precision(), etc.
Return to Top of File.#include <vstream.h> (abstract base class)
RWvios is an abstract base class. It defines an interface similar to the standard C++ class ios. However, unlike ios, it offers the advantage of not necessarily being associated with a streambuf.
This is useful for classes that cannot use a streambuf in their implementation. An example of such a class is RWXDRistream, where the XDR model does not permit streambuf type functionality.
Specializing classes that do use streambufs in their implementation (e.g., RWpistream) can usually just return the corresponding ios function.
Return to Top of File.RWvios<--RWvistream
#include <rw/vstream.h>
Class RWvistream is an abstract base class. It provides an interface for format-independent retrieval of primitives and arrays of primitives. Its counterpart, RWvostream, provides a complementary interface for the storage of these variables.
Because the interface of RWvistream and RWvostream is independent of formatting, the user of these classes need not be concerned with how variables will actually be stored or restored. That will be up to the derived class to decide. It might be done using an operating-system independent ASCII format (classes RWpistream and RWpostream), a binary format (classes RWbistream and RWbostream), or the user could define his or her own format (e.g., an interface to a network). Note that because it is an abstract base class, there is no way to actually enforce these goals -- the description here is merely the model of how a class derived from RWvistream and RWvostream should act.
See class RWvostream for additional explanations and examples of format-independent stream storage.
Return to Top of File.RWvios<--RWvostream
#include <rw/vstream.h>
Class RWvostream is an abstract base class. It provides an interface for format-independent storage of primitives and arrays of primitives. Its counterpart, RWvistream, provides a complementary interface for the retrieval of these variables.
Because the interface of RWvistream and RWvostream is independent of formatting, the user of these classes need not be concerned with how variables will actually be stored or restored. That will be up to the derived class to decide. It might be done using an operating-system independent ASCII format (classes RWpistream and RWpostream), a binary format (classes RWbistream and RWbostream), or the user could define his or her own format (e.g., an interface to a network). Note that because it is an abstract base class, there is no way to actually enforce these goals -- the description here is merely the model of how a class derived from RWvistream and RWvostream should act.
Note that there is no need to separate variables with whitespace. It is the responsibility of the derived class to delineate variables with whitespace, packet breaks, or whatever might be appropriate for the final output sink. The model is one where variables are inserted into the output stream, either individually or as homogeneous vectors, to be restored in the same order using RWvistream.
Storage and retrieval of characters requires some explanation. Characters can be thought of as either representing some alphanumeric or control character, or as the literal number. Generally, the overloaded lshift (<<) and rshift (>>) operators seek to store and restore characters preserving their symbolic meaning. I.e., storage of a newline should be restored as a newline, regardless of its representation on the target machine. By contrast, member functions get() and put() should treat the character as a literal number, whose value is to be preserved. See also class RWpostream.
Return to Top of File.